Skip to main content

Google Workspace

This tutorial show you how to integrate Google Workspace as the identity management provider for your FormKiQ installation.

We will be:

  • Configuring a Web and mobile apps in Google Workspace

  • Adding an Identify Provider into Amazon Cognito

What you’ll need​

  • Access to a FormKiQ Advanced or Enterprise installation, including administrative access

  • Administrative access to a Google Workspace

Pre-requisite​

You will need these specific configuration values:

  • CognitoUserPoolId

  • Console URL

  • Cognito domain

The CognitoUserPoolId and Console URL can be found in the Outputs tab of your FormKiQ CloudFormation installation

Cognito User Pool Id and Console Url

The Cognito domain can be found by clicking on the Cognito User Pool found on the Cognito Console.

Cognito Domain

Google Workspace​

The next step is to create an Web and mobile apps in Google Workspace. This application will be connected to Amazon Cognito and will provide authentication for the users.

Add Web and mobile apps​

To configure the Web and mobile apps:

  • Login into the Google Workspace and select the Web and Mobile Apps service

Web and Mobile Apps

  • Select "Add App" from the menu and click Add custom SAML app

Add Saml App

Single Sign-On configuration​

Now configure the SAML application by entering an Application name, description and logo.

App Details

Once the single sign-on is created, you will need to fill in the ACS URL and the Entity ID.

The ACS URL is: Your Cognito Domain/saml2/idpresponse, for example:

https://formkiq-enterprise-dev-1111111111111.auth.us-east-2.amazoncognito.com/saml2/idpresponse

The format of the Identifier (Entity ID) is:

urn:amazon:cognito:sp:<CognitoUserPoolId>

eg: urn:amazon:cognito:sp:us-east-2_MEhz4EzAZ

Saml Configuration

Setup the Primary email with the App attribute of

http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress

Under the group membership select all the Group google you want to be part of the access token and set the App attribute to be:

http://schemas.microsoft.com/ws/2008/06/identity/claims/groups

SAML Service Attributes

The app is created but User access is OFF for everyone. Click the User access to enable. Once the User access is enabled, make sure to Download Metadata, this file will be needed when setting up the Identity Provider in Cognito.

App created

App created

Amazon Cognito​

Now, we will need to configure Amazon Cognito to connect to Google Workspace.

Add Identity Provider​

We need to add Google Workspace as an Identify Provider in Amazon Cognito.

Open the AWS Console and Launch the CloudShell service.

CloudShell

Once the CloudShell command prompt opens, use the AWS CLI to add a custom attribute. This attribute will contain the group claims attribute.

aws cognito-idp add-custom-attributes \
--user-pool-id <CognitoUserPoolId> \
--custom-attributes Name=groups,AttributeDataType="String"
  • Visit the Amazon Cognito console
  • Select the User Pool, and then the Cognito Sign In Experience tab
  • Click the Add identity provider

Cognito Sign In Experience

Select the SAML Identity provider.

Cognito Add Provider

Give the provider a name, such as googleidp.

Cognito Setup Provider Name

Upload the Metadata document you downloaded from Google Workspace.

Cognito Upload Metadata document

Configure the SAML attributes.

For the email attribute, set the SAML attribute to

http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress

For the custom:groups attribute, set the SAML attribute to

http://schemas.microsoft.com/ws/2008/06/identity/claims/groups

Cognito SAML Attributes

Pre token generation​

After a successful login, we need to modify the access token and add the user's Microsoft Entra Id groups into the token. FormKiQ comes with an function that does this automatically; we just need to configure it in the Amazon Cognito.

  • Visit the Amazon Cognito console
  • Select the User Pool, and then the User pool properties tab
  • Click Add Lambda trigger

Cognito Lambda Trigger

Select Authentication and Pre token generation trigger

Cognito Add Lambda Trigger

FormKiQ deploys with a Lambda Trigger, if you search for "google".

Cognito Lambda Trigger

Select the "GoogleWorkspace" trigger and click Add Lambda trigger.

Cognito Lambda Trigger

Cognito Hosted UI​

Amazon Cognito Hosted UI provides a URL connection between Amazon Cognito and Microsoft Entra ID.

To configure Cognito Hosted UI, select the App Integration tab on the Cognito console.

Cognito App Integration

Under the Hosted UI heading, select the Edit button to configure.

Cognito Hosted UI

Set the Console Url as an allowed callback. This will allow the user to be redirected to the FormKiQ console after a successful login.

Cognito Allowed Callbacks

For the other properties:

  • Choose Google as the Identity provider

  • Set the OAuth grant type to Authorization code grant

  • Set the OpenID Connect scopes to: OpenID, Email, Profile

Cognito Hosted UI Config

Once you save the configuration, you'll see the View Hosted UI button is now enabled. This is the link to login to FormKiQ. Make note of the url and you will need to add it to the FormKiQ CloudFormation stack.

Cognito Hosted UI URL

Once you have the Cognito Hosted UI Url. Visit the CloudFormation console and select to Update your FormKiQ installation stack.

CloudFormation Update Stack

Set the Cognito Single Sign On Url to the value of the Cognito Hosted UI.

CloudFormation Cognito Single Sign On Url

Once the stack is updated you will see the Single Sign-On login button that will allow you to login through your SSO provider.

Console Single Cognito Single Sign On

Summary​

And there you have it! We have shown how easy it is to use Google Workspace as your authentication provider.

This is just the tip of the iceberg when it comes to working with the FormKiQ APIs.

If you have any questions, reach out to us on our https://github.com/formkiq/formkiq-core or https://formkiq.com.